/*
 * InputMessageListener.java    0.0.1    09/dic/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.transparency.interfaces;

import java.io.Serializable;

import org.mentalsmash.tazio.commons.identifiers.NID;
import org.mentalsmash.tazio.transparency.commons.messages.TazioMessage;

/**
 * This interface has to be implemented by every component which wants to register
 * to the dispatcher in order to receive input messages.
 * <p>
 * The interface <code>InputMessageListener</code> defines the method 
 * <code>handleMessage</code> which will be called every time a received message is passed 
 * to the dispatcher and this object is found in the input dispatching table for the 
 * corresponding message type, obviously the method will be invoked only for the objects 
 * which successfully registered to the dispatcher.
 * </p>
 * 
 * @version 0.0.1	09/dic/2009
 * @author Enrico Savioli <savioli.enrico@gmail.com>
 */
public interface InputMessageListener {
	
	/**
	 * When the {@link Dispatcher} received a message for which an object implementing 
	 * this interface is registered, this method is called, with the purpose of notifying 
	 * a listener that a message of the type it was interested into has been received.
	 * This method should contain the actions that have to be performed when the message is 
	 * received, the actual computation to be executed is specific for each listener.
	 * 
	 * @param <T>		a subclass of {@link Serializable}.
	 * @param NID		the {@link TazioNodeID} which identifies the sender of the message.
	 * @param message	the payload contained in the {@link TazioMessage} received by the 
	 * 					{@link Dispatcher}.
	 * @return			the answer to the received message.
	 */
	<T extends Serializable> Serializable handleMessage(NID nid, T message);
	
}
